http-status

What is http-status?

The http-status npm package provides a collection of HTTP status codes and their associated messages. It is useful for setting and interpreting HTTP response statuses in web applications.

What are http-status's main functionalities?

Accessing Status Codes

You can easily access standard HTTP status codes using the package. This is useful for setting response statuses in your web server.

const httpStatus = require('http-status');
console.log(httpStatus.OK); // 200
console.log(httpStatus.NOT_FOUND); // 404

Accessing Status Messages

The package allows you to retrieve the standard message associated with a given status code. This can be useful for logging or displaying human-readable status messages.

const httpStatus = require('http-status');
console.log(httpStatus['200']); // 'OK'
console.log(httpStatus['404']); // 'Not Found'

Custom Status Codes

You can add custom status codes and messages to the http-status object. This is useful if your application uses non-standard status codes.

const httpStatus = require('http-status');
httpStatus['999'] = 'Custom Status';
console.log(httpStatus['999']); // 'Custom Status'

Other packages similar to http-status

statuses

The statuses package provides similar functionality by offering a list of HTTP status codes and their associated messages. It also allows for custom status codes and messages. Compared to http-status, statuses is more lightweight and focuses solely on status codes and messages without additional features.

http-errors

The http-errors package is used to create HTTP error objects with status codes and messages. It provides more advanced error handling capabilities compared to http-status, including the ability to create custom error classes. It is useful for applications that need detailed error handling and reporting.

README

HTTP Status codes for Node.js

Utility to interact with HTTP status codes.

Usage

Once you require this module, you may call it with either an HTTP code or a message name. With an HTTP code, you will get the message name while with a message name you will get an HTTP code.

HTTP Status codes

HTTP code names, messages, and classes are respectively accessible with the property {code}_NAME, {code}_MESSAGE and {code}_CLASS. This includes all statuses in the IANA HTTP Status Code Registry, with the only addition being 418 I'm a teapot.

Extra status code are also made available that are not defined in the IANA registry, but used by popular software. They are grouped by category. Specific properties are exported by http-status under the property extra followed by the category name. Also, extra codes are merge with regular status codes and made available as modules available inside http-status/lib/{category}.

Available categories are:

unofficial

This represent a list of codes which are not specified by any standard.

iis

Microsoft's Internet Information Services (IIS) web server expands the 4xx error class to signal errors with the client's request.

nginx

The NGINX web server software expands the 4xx error class to signal issues with the client's request.

cloudflare

Cloudflare's reverse proxy service expands the 5xx error class to signal issues with the origin server.

HTTP Status code classes

In addition to HTTP status codes, this module also contains status code classes under the classes property. Similar to HTTP codes, you can access class names and messages with the property {class}_NAME and {class}_MESSAGE

API

The API is structured as follows:

100
100_NAME
100_MESSAGE
100_CLASS
CONTINUE
101
101_NAME
101_MESSAGE
101_CLASS
SWITCHING_PROTOCOLS
…
classes.
├── 1xx
├── 1xx_NAME
├── 1xx_MESSAGE
├── INFORMATIONAL
├── 2xx
├── 2xx_NAME
├── 2xx_MESSAGE
├── SUCCESSFUL
├── …
extra.
├── unofficial.
│   ├── 103
│   ├── 103_NAME
│   ├── 103_MESSAGE
│   ├── 103_CLASS
│   ├── CHECKPOINT
│   ├── …
├── iis.
│   ├── 440
│   ├── 440_NAME
│   ├── 440_MESSAGE
│   ├── 440_CLASS
│   ├── LOGIN_TIME_OUT
│   ├── …
├── nginx.
│   ├── 444
│   ├── 444_NAME
│   ├── 444_MESSAGE
│   ├── 444_CLASS
│   ├── NO_RESPONSE
│   ├── …
├── cloudflare.
│   ├── 520
│   ├── 520_NAME
│   ├── 520_MESSAGE
│   ├── 520_CLASS
│   ├── UNKNOWN_ERROR
│   ├── …

For additional information, please refer to original code.

Example usage

const status = require('http-status');

console.info(status.INTERNAL_SERVER_ERROR);
// Output: 500

console.info(status[500]);
console.info(status[status.INTERNAL_SERVER_ERROR]);
// Both output: "Internal Server Error"

console.info(status['500_NAME']);
console.info(status[`${status.INTERNAL_SERVER_ERROR}_NAME`]);
// Both output: "INTERNAL_SERVER_ERROR"

console.info(status['500_MESSAGE']);
console.info(status[`${status.INTERNAL_SERVER_ERROR}_MESSAGE`]);
// Both output: "A generic error message, given when an unexpected condition was encountered and no more specific message is suitable."

console.info(status['500_CLASS']);
console.info(status[`${status.INTERNAL_SERVER_ERROR}_CLASS`]);
// Both output: "5xx"

Example using classes

const status = require('http-status');

const responseCode = status.INTERNAL_SERVER_ERROR;

switch (status[`${responseCode}_CLASS`]) {
  case status.classes.INFORMATIONAL:
    // The responseCode is 1xx
    break;
  case status.classes.SUCCESSFUL:
    // The responseCode is 2xx
    break;
  case status.classes.REDIRECTION:
    // The responseCode is 3xx
    break;
  case status.classes.CLIENT_ERROR:
    // The responseCode is 4xx
    break;
  case status.classes.SERVER_ERROR:
    // The responseCode is 5xx
    break;

  default:
    // Unknown
    break;
}

Example using the extra property

// Accessing property from the NGINX category
const status = require('http-status');
console.info(status.extra.nginx.NO_RESPONSE)
// Accessing default HTTP status merged with NGINX status
const status = require('http-status/lib/nginx');
console.info(status.IM_A_TEAPOT);
console.info(status.NO_RESPONSE)

Example integrating Express

const express = require('express'),
      redis   = require('redis'),
      status  = require('http-status');
// New Express HTTP server
const app = express.createServer();
// Regster a route
app.get('/', (req, res) => {
  const client = redis.createClient();
  client.ping((err, msg) => {
    if (err) {
      return res.send(status.INTERNAL_SERVER_ERROR);
    }
    res.send(msg, status.OK);
  });
});
// Start the HTTP server
app.listen(3000);

Contributors

• David Worms: https://github.com/wdavidw
• Daniel Gasienica: https://github.com/gasi
• Rodrigo: [e-mail]
• Paul Vollmer: [e-mail]
• James Barcellano: https://github.com/ckeboss

This package is developed by Adaltas.

Developers

To automatically generate a new version:

yarn run release

Package publication is handled by the CI/CD with GitHub action.

Changelog

1.8.1 (2024-10-21)

• Revert changes introduced by 1.8.0